<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Receiving Messages</title>
<link href="../style.css" rel="stylesheet" type="text/css">
</head>
<body>
<div class="header">
<h1>QuickFIX/J User Manual</h1>
</div>

<H2>Receiving Messages</H2>
<p> Most of the messages you will be interested in looking at will be arriving
  in your overloaded <code>fromApp</code> function of your application. You can get
  fields out of messages with different degrees of type safety. The type in question
  here is the FIX message type. When the application passes you a <code>Message</code> class,
  the Java type checker has no idea what specific FIX message it is, you must
  determine that dynamically. There is, however, a way we can make Java aware
  of this type information. First we will cover how to dynamically retreive fields
  from a message, then we will show you the prefered type safe way. Keep in mind
  that all messages have a header and a trailer. If you want to see fields in
  them, you must first call <code>getHeader()</code> or <code>getTrailer()</code> to get
  access to them. Otherwise you access them just like in the message body.</p>
<H3>Least Type Safe</H3>
<p> This method of retreiving data from messages is <em>strongly discouraged</em> and
  is generally only useful for writing more low level interfaces for other languages
  and middleware. </p>
<pre class="code">
import quickfix.*;

public void fromApp(Message message, SessionID sessionID)
  throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {

  StringField field = new StringField(44);
  message.getField(field);
}
</pre>
<H3>More Type Safe</H3>
<p> A way to add some type safety to this is by using field classes that represent
  all the FIX defined fields. This is sometimes useful in an application, but
  is generally only used within code segments that need to be version independent
  (meaning versions of FIX). For example, our Session class is implemented using
  mostly these. It is generally not recomended for most applications. This will
  also get fields as their appropriate type, not just as strings. </p>

<pre class="code">
import quickfix.*;
import quickfix.field.*;

public void fromApp(Message message, SessionID sessionID)
  throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {

  Price price = new Price();
  message.getField(price);

  ClOrdID = new ClOrdID();
  message.getField(clOrdID);
}
</pre>

<H3>Most Type Safe... DO THIS!</H3>
<p> Here is the most type safe and <em>highly encouraged</em> method for retreiving
  data from a message. QuickFIX has message classes that correlate to all the
  messages defined in the spec. They are, just like the field classes, generated
  directly off of the FIX specifications. To take advantage of this, you must
  break the messages out with the supplied <code>MessageCracker</code>. Also notice
  we are no longer using a generic <code>Message</code> class and we are now using <code>get</code> instead
  of <code>getField</code>. Keep in mind you can still use <code>getField</code> as all of
  these classes derive from <code>Message</code> </p>
<pre class="code">
import quickfix.*;
import quickfix.field.*;

public void fromApp(Message message, SessionID sessionID)
      throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {

  crack(message, sessionID);
}

public void onMessage(quickfix.fix42.NewOrderSingle message, SessionID sessionID)
      throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {

  ClOrdID clOrdID = new ClOrdID();
  message.get(clOrdID);

  ClearingAccount clearingAccount = new ClearingAccount();
  message.get(clearingAccount);
}

public void onMessage(quickfix.fix42.OrderCancelRequest message, SessionID sessionID)
      throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {

  ClOrdID clOrdID = new ClOrdID();
  message.get(clOrdID);

  // compile time error!! field not defined for OrderCancelRequest
  ClearingAccount clearingAccount = new ClearingAccount();
  message.get(clearingAccount);
}
</pre>
<p> In order to use this you must use the <code>MessageCracker</code> as a mixin to
  your application. This will provide you with the <code>crack</code> function and
  allow you to overload specific message functions. Any function you do not overload
  will by default throw an <code>UnsupportedMessageType</code> exception</p>
  <p>
  Define your application like this: </p>
<pre class="code">
import quickfix.Application;
import quickfix.MessageCracker;

public class MyApplication
  extends MessageCracker implements quickfix.Application
</pre>
<p>
QuickFIX/J version 1.16 or newer supports a new version of <code>MessageCracker</code> that dynamically discovers message handling method using either a method naming convention (similar to earlier versions of QuickFIX/J)
or by tagging handlers methods with the <code>@Handler</code> annotation.
</p>
<p>
Examples...
</p>
<pre class="code">
import quickfix.Application;
import quickfix.MessageCracker;

public class MyApplication extends MessageCracker implements quickfix.Application
{
    public void fromApp(Message message, SessionID sessionID)
            throws FieldNotFound, UnsupportedMessageType, IncorrectTagValue {
        crack(message, sessionID);
    }

    // Using annotation
    @Handler
    public void myEmailHandler(quickfix.fix50.Email email, SessionID sessionID) {
        // handler implementation
    }

    // By convention (notice different version of FIX. It's an error to have two handlers for the same message)
    // Convention is "onMessage" method with message object as first argument and SessionID as second argument
    public void onMessage(quickfix.fix44.Email email, SessionID sessionID) {
        // handler implementation
    }
}
</pre>
<p>
If you'd rather use composition rather than inheritance of the <code>MessageCracker</code> you can construct a message cracker with a delegate object.
The delegate message handler methods will be automatically discovered. Message crackers for each FIX version are still generated for backward compatibility
but it's more efficient to define the specific handlers you need. The generated classes define handlers for all messages defined by that version of FIX.
This requires the JVM to load those classes when the cracker is loaded. Most applications only need to handle a small subset of the messages defined by
a FIX version so loading all the messages classes is excessive overhead in those cases.
<p>

<H3>Support for Functional Interfaces</H3>
<p>
    If you prefer using lambda expressions in handling received messages, then
    <code>ApplicationFunctionalAdapter</code> or <code>ApplicationExtendedFunctionalAdapter</code> can be used to
    register reactions to events the application is interested in. They also allow registering the interests in a given
    message type in a type-safe manner.
<p>

<pre class="code">
import quickfix.ApplicationFunctionalAdapter;
import quickfix.SessionID;

public class EmailForwarder {
    public void init(ApplicationFunctionalAdapter adapter) {
        adapter.addOnLogonListener(this::captureUsername);
        adapter.addFromAppListener(quickfix.fix44.Email.class, (e , s) -> forward(e));
    }

    private void forward(quickfix.fix44.Email email) {
        // implementation
    }

    private void captureUsername(SessionID sessionID) {
        // implementation
    }
}
</pre>
<p>
    <code>ApplicationFunctionalAdapter</code> and <code>ApplicationExtendedFunctionalAdapter</code> support multiple
    registration to the same event, and the registered callbacks are invoked in the FIFO manner. However FIFO
    cannot be guaranteed between registration with specific message type (e.g. <code>quickfix.fix44.Email</code>) and
    that without specific message type. For example, there is no invocation order guarantee between the following two
    callbacks:
<p>

<pre class="code">
    adapter.addFromAppListener((e , s) -> handleGeneral(e));

    adapter.addFromAppListener(quickfix.fix44.Email.class, (e , s) -> handleSpecific(e));
</pre>

<div class="footer">More information at <a href="http://www.quickfixj.org/">www.quickfixj.org</a></div>

</body>
</html>
